docs(server): design the SubjectService token principal (RIG-2863) - #868

…(RIG-2863)

Round-3 review returned 0 high / 4 medium / 3 low. All six round-2 fixes held;
the blockers were three new grounded defects in round-2's reconcile-execution-
context paragraph (the WithSystemRole ruling itself is correct and stands) plus
one ledger-recording judgment call Matt ruled on.

- M1 (medium): the paragraph justified WithSystemRole by claiming FORCE RLS
  binds even the owner at boot. False — the owner connection is a superuser and
  a superuser bypasses even FORCE (0001_init.sql:848-851; rls_pgtest_test.go:
  282-284). Restated on the true, superuser-independent reason: the reconcile
  takes the compass_app path, a non-owner non-BYPASSRLS role confined to the
  bootstrap tenant, so a row under another tenant is silently skipped without
  WithSystemRole.
- M2 (medium): the prescribed two-tenant same-name test is unconstructible —
  `secrets.name` is a global PRIMARY KEY (0001_init.sql:396), so at most one row
  per configured name exists deployment-wide. Reframed the motivation and the
  test to the real case: a row declared under a NON-bootstrap tenant.
- M3 (medium): corrected the "fifth entrypoint" miscount — the shipped tree
  arms WithSystemRole at THREE call sites (consumer.go:316, hub.go:753/814), and
  hub.go:814 (forge-notification-ack) is already a BYPASSRLS site DL-315's four
  names omit. Enumeration restated against the shipped set.
- L1/L2/L3 (low): cite the arming code (armQueue/beginTenantTx) not just the
  WithSystemRole entrypoint; quote DL-315 verbatim; move the reconcile test into
  T0's Tests enumeration.
- M4 -> OQ-5 (Matt-ruled: a new ledger row): the DL-315 BYPASSRLS allow-list
  widening lands as DL-326 (Refines DL-315, which stays Active), restating the
  true shipped entrypoint set incl. the previously-unledgered forge-notification-
  ack arm. Discoverability at the surface where the BYPASSRLS-audit question gets
  asked, over prose buried in an at-rest-encryption record.

Ledger-collision renumber: main's #870 (RIG-3096) merged its own DL-324 (forge
live-test app-actor) after this stack forked. Renumbered this addendum's ledger
rows to the next free sequential ids — the `gateway_credentials` encryption
decision is DL-325 (was DL-324), the BYPASSRLS allow-list widening stays DL-326,
and the sibling SubjectService PR (#868) takes DL-327 — leaving main's DL-324
untouched.

Additive review-fix commit atop the round-2 fix.

Ledger-impact: DL-325 (encryption, renumbered from DL-324), DL-326 (new, Refines DL-315)
Spec-impact: none
Refs RIG-2863
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…863)

Review of #868 returned 0 high / 1 medium / 2 low. Citations (16/16) and the
SubjectService ledger row were a clean pass; the blocker was executor-contract
coherence.

- F1 (medium): the Plan framed all five tasks as one "PR2 executor contract",
  but T4 (the service-door mount) targets a Server surface that does not exist
  in the tree yet, and no corpus task owns minting a SubjectService token — so
  the class as written ships unreachable. Reframed the Plan into two scopes: the
  enum half (T1/T2/T3/T5) lands now as PR2 (the urgent half — enum number + CHECK
  are painful to change once token rows exist); the door half (T4) lands WITH the
  RIG-2863 (RIG-1715 T2) service surface it mounts on, ordered after it. Added
  OQ-3 naming where token issuance lives (the RIG-2863 T4 slice, an
  IssueServiceToken mirroring MintRunnerToken) so an executor never improvises a
  mint path on a security-critical door.
- F2 (low): citation span `lines 348-350` -> `348-351` (the quoted "disable)"
  falls on 351).
- F3 (low, pre-existing): noted that `runnerhub.RunnerTokenRegistered` is the one
  token-store consumer outside the kind-gated door contract — flagged for the T4
  executor to kind-check or document, out of scope for this record.

Ledger-collision renumber: main's #870 (RIG-3096) merged its own DL-324 (forge
live-test app-actor) after this stack forked, and the sibling encryption PR
(#859) took DL-325/DL-326. Renumbered this record's SubjectService row to the
next free id, DL-327 (was DL-325), leaving main's DL-324 untouched.

Additive review-fix commit.

Ledger-impact: DL-327 (SubjectService, renumbered from DL-325)
Spec-impact: none
Refs RIG-2863

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…-3238)

ReviewDesign869 returned 1 high / 2 medium / 4 low on PR #869. Grounding
fidelity was clean (all code + cross-record citations verify at source);
these are ledger-collision and plan-completeness fixes. All folded; the two
mediums each also surface a load-bearing fork to Matt as a new OQ rather than
being decided here.

- HIGH (ledger collision): DL-326's Decision cell cited DL-325, an unlanded
  number double-claimed by #804 (RIG-3070) and #868 (RIG-2863). Since #868 is
  review-ready it may take DL-325 for an unrelated decision, and the cell is
  immutable after append. Re-cite the runner trust-model split by name+issue
  (RIG-3070 / PR #804), not the contested number, and add a Global Constraint
  ID-allocation + freeze-order note (mirroring the sibling embedded-revival
  record's GC6): re-grep main's ledger tail before landing, and the record
  does not depend on #804 landing first.
- MEDIUM (T-4 premise gap): removing podman-machine removes the Linux VM the
  runner runs IN on macOS today (compass-local-dev:194-205 ruled the runner
  runs INSIDE the VM), so apple-container forces the runner to run natively on
  darwin. Add a T-1(f) spike leg, an Approach reason-2 caveat, a T-4 scope
  note, and OQ-12 (load-bearing Matt fork: does a NO re-open adoption?).
- MEDIUM (T-2 podman surface): the stack has a second hard-coded podman shell
  (postgres_container.go:246-259 + collector_container.go:62) and ImageEnsurer
  is podman-hardwired at its production constructor (image.go:44-45). DL-260
  keeps postgres a rootless-podman container, so a macOS host still needs
  podman for the stack. Widen T-2's off-interface enumeration, concede the
  scoped "no machine" win in Approach reason 2, and add OQ-13 (Matt fork:
  postgres to apple-container, or --database-external as the macOS default?).
- LOW x4: nine-verbs wording (Resize is the ninth, not a tenth); image.go
  ImageExists citation span (:713, outside the cited :681-684); the
  OQ-1..OQ-4 gate carve-out for OQ-5's judgment call; DL-326 record link
  gains the §Approach anchor for the one-hop convention.

Checks: markdownlint 0 errors; design-ledger-gate OK (291 rows, 122 headers).
Status stays Draft — freezes Active on merge.

Refs RIG-3238
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…-3238)

ReviewDesign869 returned 1 high / 2 medium / 4 low on PR #869. Grounding
fidelity was clean (all code + cross-record citations verify at source);
these are ledger-collision and plan-completeness fixes. All folded; the two
mediums each also surface a load-bearing fork to Matt as a new OQ rather than
being decided here.

- HIGH (ledger collision): DL-326's Decision cell cited DL-325, an unlanded
  number double-claimed by #804 (RIG-3070) and #868 (RIG-2863). Since #868 is
  review-ready it may take DL-325 for an unrelated decision, and the cell is
  immutable after append. Re-cite the runner trust-model split by name+issue
  (RIG-3070 / PR #804), not the contested number, and add a Global Constraint
  ID-allocation + freeze-order note (mirroring the sibling embedded-revival
  record's GC6): re-grep main's ledger tail before landing, and the record
  does not depend on #804 landing first.
- MEDIUM (T-4 premise gap): removing podman-machine removes the Linux VM the
  runner runs IN on macOS today (compass-local-dev:194-205 ruled the runner
  runs INSIDE the VM), so apple-container forces the runner to run natively on
  darwin. Add a T-1(f) spike leg, an Approach reason-2 caveat, a T-4 scope
  note, and OQ-12 (load-bearing Matt fork: does a NO re-open adoption?).
- MEDIUM (T-2 podman surface): the stack has a second hard-coded podman shell
  (postgres_container.go:246-259 + collector_container.go:62) and ImageEnsurer
  is podman-hardwired at its production constructor (image.go:44-45). DL-260
  keeps postgres a rootless-podman container, so a macOS host still needs
  podman for the stack. Widen T-2's off-interface enumeration, concede the
  scoped "no machine" win in Approach reason 2, and add OQ-13 (Matt fork:
  postgres to apple-container, or --database-external as the macOS default?).
- LOW x4: nine-verbs wording (Resize is the ninth, not a tenth); image.go
  ImageExists citation span (:713, outside the cited :681-684); the
  OQ-1..OQ-4 gate carve-out for OQ-5's judgment call; DL-326 record link
  gains the §Approach anchor for the one-hop convention.

Checks: markdownlint 0 errors; design-ledger-gate OK (291 rows, 122 headers).
Status stays Draft — freezes Active on merge.

Refs RIG-3238
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…sign (RIG-3238)

ReviewDesign869r2 verified all 7 round-1 findings CLOSED but caught two
mediums the round-1 fold's own new prose introduced. Both are mechanical
text corrections with no design consequence.

- MEDIUM (guard-bullet facts): the ID-allocation/freeze-order Global
  Constraint bullet had wrong PR->DL attributions on every clause. Ground
  truth (verified via gh pr diff + main's ledger): main's tail ends at DL-324
  (landed by #870, merged); DL-325 is claimed by #804 (RIG-3070, draft) AND
  #859 (RIG-2863); DL-326 -- this record's own number -- is claimed by #859,
  which is review-ready (NOT draft). The bullet missed the real live collision
  (#859 on DL-326) and named #868 (which actually claims DL-327). Rewrote the
  factual clauses to match; kept the two correct load-bearing clauses (the
  MUST-re-grep-before-landing instruction and does-NOT-depend-on-#804). The
  immutable DL-326 cell was already merge-order-safe (name+issue cite), so
  this only corrected mutable prose.
- MEDIUM (unknown-count consistency): round-1 widened the ledger cell from
  five to six unknowns (adding runner-on-darwin / OQ-12) but left three "five"
  sites in the record body: the Why-STAGED enumeration, the reject-default
  alternative, and the T-1 task heading. Aligned all three to six + OQ-12, and
  aligned the threat classification (OQ-1, OQ-2, and OQ-12 threaten adoption)
  with the cell's widened re-open trigger.
- LOW: re-wrapped two range-overwrite orphan lines to the file's ~72-col width.

Checks: markdownlint 0 errors; design-ledger-gate OK (291 rows, 122 headers).
Status stays Draft -- freezes Active on merge.

Refs RIG-3238
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…(RIG-2863)

Round-3 review returned 0 high / 4 medium / 3 low. All six round-2 fixes held;
the blockers were three new grounded defects in round-2's reconcile-execution-
context paragraph (the WithSystemRole ruling itself is correct and stands) plus
one ledger-recording judgment call Matt ruled on.

- M1 (medium): the paragraph justified WithSystemRole by claiming FORCE RLS
  binds even the owner at boot. False — the owner connection is a superuser and
  a superuser bypasses even FORCE (0001_init.sql:848-851; rls_pgtest_test.go:
  282-284). Restated on the true, superuser-independent reason: the reconcile
  takes the compass_app path, a non-owner non-BYPASSRLS role confined to the
  bootstrap tenant, so a row under another tenant is silently skipped without
  WithSystemRole.
- M2 (medium): the prescribed two-tenant same-name test is unconstructible —
  `secrets.name` is a global PRIMARY KEY (0001_init.sql:396), so at most one row
  per configured name exists deployment-wide. Reframed the motivation and the
  test to the real case: a row declared under a NON-bootstrap tenant.
- M3 (medium): corrected the "fifth entrypoint" miscount — the shipped tree
  arms WithSystemRole at THREE call sites (consumer.go:316, hub.go:753/814), and
  hub.go:814 (forge-notification-ack) is already a BYPASSRLS site DL-315's four
  names omit. Enumeration restated against the shipped set.
- L1/L2/L3 (low): cite the arming code (armQueue/beginTenantTx) not just the
  WithSystemRole entrypoint; quote DL-315 verbatim; move the reconcile test into
  T0's Tests enumeration.
- M4 -> OQ-5 (Matt-ruled: a new ledger row): the DL-315 BYPASSRLS allow-list
  widening lands as DL-326 (Refines DL-315, which stays Active), restating the
  true shipped entrypoint set incl. the previously-unledgered forge-notification-
  ack arm. Discoverability at the surface where the BYPASSRLS-audit question gets
  asked, over prose buried in an at-rest-encryption record.

Ledger-collision renumber: main's #870 (RIG-3096) merged its own DL-324 (forge
live-test app-actor) after this stack forked. Renumbered this addendum's ledger
rows to the next free sequential ids — the `gateway_credentials` encryption
decision is DL-325 (was DL-324), the BYPASSRLS allow-list widening stays DL-326,
and the sibling SubjectService PR (#868) takes DL-327 — leaving main's DL-324
untouched.

Additive review-fix commit atop the round-2 fix.

Ledger-impact: DL-325 (encryption, renumbered from DL-324), DL-326 (new, Refines DL-315)
Spec-impact: none
Refs RIG-2863
Co-authored-by: Matt Wilkinson <matt@rigel.build>